---
type: integration
title: '@astrojs/alpinejs'
description: '@astrojs/alpinejs 프레임워크 통합을 사용하여 Astro 프로젝트에서 컴포넌트 지원을 확장하는 방법을 알아보세요.'
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/alpinejs/'
category: renderer
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

이 **[Astro 통합][astro-integration]** 은 프로젝트에 [Alpine.js](https://alpinejs.dev/)를 추가하므로 페이지 어디에서나 Alpine.js를 사용할 수 있습니다.

## 설치

Astro에는 공식 통합 설정을 자동화하는 `astro add` 명령이 포함되어 있습니다. 원하는 경우 대신 [통합을 수동으로 설치](#수동으로-설치하기)할 수 있습니다.

`@astrojs/alpinejs`를 설치하려면 프로젝트 디렉터리에서 다음을 실행하고 프롬프트를 따르세요.

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npx astro add alpinejs
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm astro add alpinejs
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn astro add alpinejs
    ```
  </Fragment>
</PackageManagerTabs>

문제가 발생하면 [GitHub에 언제든지 보고](https://github.com/withastro/astro/issues)하고 아래 수동 설치 단계를 시도해 보세요.

### 수동으로 설치하기

먼저 `@astrojs/alpinejs` 패키지를 설치하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npm install @astrojs/alpinejs
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm add @astrojs/alpinejs
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn add @astrojs/alpinejs
    ```
  </Fragment>
</PackageManagerTabs>

대부분의 패키지 관리자는 관련 피어 종속성도 설치합니다. 그러나 Astro를 시작할 때 "Cannot find package 'alpinejs'" (또는 이와 유사한) 경고가 표시되면 Alpine.js를 직접 설치해야 합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install alpinejs @types/alpinejs
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add alpinejs @types/alpinejs
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add alpinejs @types/alpinejs
  ```
  </Fragment>
</PackageManagerTabs>

그런 다음 `integrations` 속성을 사용하여 `astro.config.*` 파일에 통합을 적용합니다.

```js ins="alpine()" title="astro.config.mjs" ins={2}
import { defineConfig } from 'astro/config';
import alpine from '@astrojs/alpinejs';

export default defineConfig({
  // ...
  integrations: [alpine()],
});
```

## 구성 옵션

### `entrypoint`

`entrypoint` 옵션을 루트 상대 가져오기 지정자 (예: `entrypoint: "/src/entrypoint"`)로 설정하여 Alpine을 확장할 수 있습니다.

이 파일의 기본 내보내기는 시작하기 전에 Alpine 인스턴스를 허용하는 함수여야 합니다. 이를 통해 고급 사용 사례에 맞게 사용자 정의 지시어, 플러그인, 기타 맞춤 설정을 사용할 수 있습니다.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import alpine from '@astrojs/alpinejs';

export default defineConfig({
  // ...
  integrations: [alpine({ entrypoint: '/src/entrypoint' })],
});
```

```js title="src/entrypoint.ts"
import type { Alpine } from 'alpinejs'
import intersect from '@alpinejs/intersect'

export default (Alpine: Alpine) => {
    Alpine.plugin(intersect)
}
```

## 사용하기

통합이 설치되면 모든 Astro 컴포넌트에서 [Alpine.js](https://alpinejs.dev/) 지시어와 구문을 사용할 수 있습니다. Alpine.js 스크립트는 웹사이트의 모든 페이지에 자동으로 추가되고 활성화됩니다. `<head>` 페이지에 플러그인 스크립트를 추가하세요.

다음 예시에서는 [Alpine의 Collapse 플러그인](https://alpinejs.dev/plugins/collapse)을 추가하여 단락 텍스트를 확장하고 축소합니다.

```astro title="src/pages/index.astro" ins={6} ins="x-collapse"
---
---
<html>
	<head>
		<!-- ... -->
		<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/collapse@3.x.x/dist/cdn.min.js"></script>
	</head>
	<body>
    <!-- ... -->
		<div x-data="{ expanded: false }">
			<button @click="expanded = ! expanded">Toggle Content</button>
			<p id="foo" x-show="expanded" x-collapse>
        Lorem ipsum
			</p>
		</div>
	</body>
</html>
```

## TypeScript용 Intellisense

`@astrojs/alpine` 통합은 전역 window 객체에 `Alpine`을 추가합니다. IDE 자동 완성을 위해 `src/env.d.ts` 파일에 다음을 추가하세요:

```ts title="src/env.d.ts"
interface Window {
  Alpine: import('alpinejs').Alpine;
}
```

## 예시

* [Astro Alpine.js 예시](https://github.com/withastro/astro/tree/latest/examples/framework-alpine)는 Astro 프로젝트에서 Alpine.js를 사용하는 방법을 보여줍니다.

[astro-integration]: /ko/guides/integrations-guide/
[astro-ui-frameworks]: /ko/guides/framework-components/#컴포넌트-프레임워크-사용하기